________________________________________________________________________
                                               Chapter 11: Commands   99
    ________________________________________________________________________


    CHAPTER ELEVEN: COMMANDS

    This chapter provides an alphabetical listing of all the commands
    available in PADtalk. Each command is described in detail, its syntax is
    given and examples are offered.

    Command:                Description:
    -----------------------------------------------------------------------
    add                     Add to a container
    answer                  Ask a question with buttons as choices
    ask                     Ask a question, allowing user to type response
    close                   Close a file
    convert                 Convert date and time data to a different format
    delete                  Delete a chunk from a container
    dial                    Dial a number with a modem
    divide                  Divide a container by an amount
    do                      Execute an expression as a statement
    edit script             Edit the script of a HyperPAD object
    find                    Find text somewhere in your pad
    flushCache              Write changed pages from memory to disk
    fxShow                  Execute the Show Partner F/X runtime
    get                     Put an expression into the local variable "it"
    global                  Declare a global variable
    go                      Change to another page, background, or pad
    hide                    Hide an object
    hilite                  Highlights text in a field
    multiply                Multiply a container by an amount
    noSound                 Turn the speaker off (from sound or play)
    play                    Play music in the background
    playBack                Play back previously recorded keystrokes
    pop page                Change to a previously saved page
    print                   Print information from a pad



    ________________________________________________________________________
                                               Chapter 11: Commands   100
    ________________________________________________________________________


    Command:                Description:
    -----------------------------------------------------------------------

    push page               Save a page for later recovery using pop
    put                     Copy information to a container
    query                   Create a subset of pages based on criteria
    read                    Read chunks from a file
    record                  Record keystrokes for later playback
    run                     Run another program
    send                    Send a message to another object
    set                     Modify object properties
    setDefaultPopupColors   Sets the popup colors to the default
    SetPopupColors          Sets the colors used to display popups
    show                    Make an object visible
    sort                    Sort the pad
    sound                   Turn the speaker on a a particular frequency
    subtract                Subtract an expression from a container
    visual                  Set up an effect for the next page change
    wait                    Wait some number of miliseconds
    write                   Write text to a file

    -----------------------------------
    ADD

    Syntax:
    add <expression> to <destination>;

    Purpose: The add command adds the value of the expression to the value
    of the destination and places the result into the destination.

    The <expression> must evaluate to a number or be a container holding a
    number. The <destination> must be a container.

    Note: You will receive a runtime error if either the <expression> or the
    <destination> is not a number.

    Examples:

    add 5 to page field 23;

    add 45.67 to word 2 of page field 1;



    ________________________________________________________________________
                                               Chapter 11: Commands   101
    ________________________________________________________________________


    -----------------------------------
    ANSWER

    Syntax:
    answer question [with <button1> [,<button2> [,<button3>]]];

    Purpose: The answer command allows you to create dialog boxes that ask a
    question. The user responds by choosing one of the buttons supplied. The
    dialog box is similar to other HyperPAD dialog boxes and is always
    centered on the page. You can specify up to 3 buttons to choose from.

    The Answer dialog box looks like this:

 ÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ¿
 ³                                                                       ³
 ³ **** The Printed Documentation has a picture or screen shot here **** ³
 ³                                                                       ³
 ÀÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÙ
    

    The <question> is the text within the dialog box. The text can be many
    lines long, in which case it is word-wrapped. Use carriage returns to
    improve the readability of your messages.

    The user can choose one of up to three buttons you supply in <button1>,
    <button2>, <button3>. If you don't specify any buttons to choose from,
    HyperPAD uses the two default buttons: <<Ok>> and <Cancel>.

    When the user accesses the dialog box, it remains on-screen until a
    choice is selected. After the user responds, either by selecting a
    choice or pressing ESC, the dialog box is removed and the selected
    button text is placed into the local variable it. For example, if the
    user selects <<Ok>>, it will contain "Ok". If the user selects <Cancel>,
    it will contain "cancel". If the user presses ESC, then the variable it
    will be empty.



    ________________________________________________________________________
                                               Chapter 11: Commands   102
    ________________________________________________________________________


    Examples:

    answer "Ok to quit?";

    answer "Continue printing?" with "Yes","No";

    answer "What color?" with "red","blue","green";

    answer "Error printing!" with "Ok";

    The following handler asks the user if it is Ok to quit:

    handler cancel;
    begin
      "Ok to quit?" with "Yes","No";
      if it is "Yes" then quit;
    end;

    See Also: ask

    -----------------------------------
    ASK

    Syntax:
    ask question [with <default response>];

    Purpose: The ask command allows you to gather information from the pad's
    user by creating a dialog box in which the user types a response. The
    Ask dialog box presents a question as a prompt, a text box in which to
    type a response, and <<Ok>> and <Cancel> buttons.

 ÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ¿
 ³                                                                       ³
 ³ **** The Printed Documentation has a picture or screen shot here **** ³
 ³                                                                       ³
 ÀÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÙ
    

    When the user presses the <<Ok>> button, the response is put in the
    local variable it. If there is no response, or <Cancel> is selected, the
    local variable it will be empty.



    ________________________________________________________________________
                                               Chapter 11: Commands   103
    ________________________________________________________________________


    If you supply a default answer, it is presented in the text box as the
    default response. Then, when the user begins typing in a different
    response, the proposed answer is replaced by the typed one.

    Note: You cannot change the proposed buttons in the Ask dialog box. They
    will always be Ok and Cancel.

    Examples:

    ask "What is your name?";

    The following uses ask to go to the page that the user specifies. If the
    user cancels the dialog box, the process stops:

    handler select;
    begin
      while true do
        begin
          ask "Go to which page?" with currentPage + 1;
          if it is empty then exit;
          go to page it;
        end;
    end;

    See Also: answer

    -----------------------------------
    CLOSE

    Syntax:
    close <file number>;

    Purpose: The close command closes a previously opened file. All files
    must be closed after you are finished with them. (You can open a file
    using the create and open functions.)

    Examples:

    close fh;

    The following example writes the contents of field 1 to a file:

    put create("data.dat") into fh;
    write field 1 to fh;
    close fh;

    Note: This command sends the close message.

    See Also: create, open, read, write



    ________________________________________________________________________
                                               Chapter 11: Commands   104
    ________________________________________________________________________


    -----------------------------------
    CONVERT

    Syntax:
    convert container to <format> [and <format>];
    convert var1 to seconds;
    convert var1 to dateItems;
    convert var1 to [long | short | abbreviated] date;
    convert var1 to [long | short] time;
    convert var1 to [long | short | abbreviated] date and
    [long | short] time;

    Purpose: This command converts dates to different formats. The range of
    dates HyperPAD understands starts from Saturday, January 1, 1583 -- the
    starting date of the Gregorian Calendar. Using convert, you can input a
    numerical date, like "5/8/90", and translate it to written form, like
    "Tuesday, May 8, 1990".

    The following are explanations of target formats using January 1, 1990
    at 5:00:00 PM as an example.

    Date Format:                  Example:
    -----------------------------------------------------------------
    date (same as short date)     1-1-90 The dash (-) is the only date
                                  separator output by convert

    long date                     Monday, January 1, 1990

    abbreviated date              Mon, Jan 1, 1990

    seconds                       12843766800 The number of seconds since
                                  1-1-1583

    time                          5:00 PM

    long time                     5:00:00

    dateItems                     1990,1,1,17,0,0,2 (year, month, day, hour,
                                  minute, second, day of week)



    ________________________________________________________________________
                                               Chapter 11: Commands   105
    ________________________________________________________________________


    Container formats:  The power of convert is derived from the flexible
    representation of the container being converted. The following are
    allowed:

    1.  Both the dash and slash (-,/) can be used as date separators.

    2.  Date item lists can be modified creating an invalid date and then
    normalized by converting it to another format. The following example
    modifies the dateItems list to figure out the date 40 days from today:

    get the seconds;  --get today's date and time
    convert it to dateItems;  --convert to date item list
    add 40 to item 3 of it;   --add 40 days
    convert it to longDate;   --normalize
    answer "40 days from now is" && it;

    The next example modifies the dateItems list to figure out what the date
    and time will be 18 hours from now:

    get the seconds;  --get today's date in seconds
    convert it to dateItems;  --convert to date item list
    add 18 to item 4 of it;  --add 18 hours
    convert it to longDate and time;  --normalize
    answer "18 hours from now is" && it;

    3.  The formats that you can convert from are loose. The following are
    suitable formats for convert:

    Example:                   Format:
    -----------------------------------------------------
    Jan 1, 1990                date

    January 1, 1990            date

    Jan 1, 90                  date

    Jan 1, 1990 11:20          date and time

    Mon, Jan 1, 90 11:20 AM    date and time

    11:20                      time

    11:20 PM                   time

    11:20 Jan 1, 1990          time and date

    11:20 Mon, Jan 1, 1190     time and date

    65                         seconds

    1990,1,1,17,00,2           dateItems



    ________________________________________________________________________
                                               Chapter 11: Commands   106
    ________________________________________________________________________


    Examples:

    This function returns the day of the week of the first day of the
    current month:

    function firstDay;
    begin
      get the date;
      convert it to dateItems; --represent as date items
      put 1 into item 3 of it; -- put 1 as day of the month
      convert it to long date; -- convert to string
      return word 1 of it; -- return day of week
    end;

    This handler computes tomorrows date:

    handler tomorrow;
    begin
      get the seconds;
      add 60 * 60 * 24 to it;
      convert it to long date;
      answer "Tomorrows date is" && it;
    end;

    Comments: The following months and days of the week and their
    abbreviations are recognized by HyperPAD:

    Keyword:               Abbreviation:
    ------------------------------------------
    january                jan

    february               feb

    march                  mar

    april                  apr

    may                    may

    june                   jun

    july                   jul

    august                 aug

    september              sep

    october                oct

    november               nov

    december               dec



    ________________________________________________________________________
                                               Chapter 11: Commands   107
    ________________________________________________________________________


    Keyword:               Abbreviation:
    ------------------------------------------
    sunday                 sun

    monday                 mon

    tuesday                tue

    wednesday              wed

    thursday               thu

    friday                 fri

    saturday              sat

    See Also: time, longTime(), seconds(), date(), longDate()

    -----------------------------------
    DELETE

    Syntax:
    delete <chunk> from <container>;
    delete <container;>

    Purpose: The delete command can be used to remove a chunk of
    information, or all the information from a container. The number of
    characters removed from the container is specified by using a chunking
    expression involving items, words, lines or characters (see the section
    on Chunking).

    If you do not specify a chunk to be deleted, HyperPAD will delete all of
    the characters in the container. For example:

    delete page field 1;

    delete salesTax;

    Chunks are defined by the characters that are around them. When you
    delete items and lines from a container, you also remove the delimiter
    (either a comma or carriage return) that defines it. For example,
    deleting a line from a field would delete the carriage return at the end
    of the line (if there is one).

    The following example deletes items from a field. Suppose field 1
    contains "Jim, John, Sally, Lisa". The following statement:

    delete item 2 to 3 of field 1;

    results in field 1 containing "Jim, Lisa". Note that "John, Sally," was
    deleted, including the commas.



    ________________________________________________________________________
                                               Chapter 11: Commands   108
    ________________________________________________________________________


    When to use it:  When you want to remove a specific part of a
    container's value while keeping the rest intact.

    Examples:

    delete myvar;
    delete page field 5;  -- removes all chars in page field 5

    The following example deletes the current line from page field 1:

    get the currentLine of page field 1;
    delete line it from page field 1;

    The next example deletes all of the lines that contain the word "BAD".
    Care is taken to make sure that the loop is performed the correct number
    of times because the number of lines change as we delete lines:

    put the number of lines of page field 1 into numlines;
    put 1 into i;
    while i  numlines do
      begin
        if line i of page field 1 contains "BAD" then
          begin
            delete line i of page field 1;
            subtract 1 from numlines;
          end
        else add 1 to i;
      end;

    -----------------------------------
    DIAL

    Syntax:
    dial [pulse | tone | noHayes] <number> [with <modem commands>];

    Purpose: With dial, you can call any telephone number (using  a modem)
    for voice communication. Specify pulse or tone dialing, depending on
    your phone service (the default is pulse).

    While dialing, you are presented with a message, indicating that dialing
    is in progress

    If the dial is successful, a dialog box will be displayed requesting
    that you pick up the phone. The modem will remain connected until this
    dialog box is removed (by selecting the <<Ok>> button).

    The dial command performs the following steps when dialing the phone:

    1.  The modem port is initialized using the current settings of the
    global properties modem, dataBits, stopBits, parity, and baud.



    ________________________________________________________________________
                                               Chapter 11: Commands   109
    ________________________________________________________________________


    2.  The modem is initialized using the Hayes modem command "ATV1E0",
    causing the modem to echo responses to HyperPAD. HyperPAD waits for the
    modem to respond "Ok".

    3.  The <expression> is prefixed with "ATDP" or "ATDT" depending on if
    you specified tone or pulse. Specifying <modem commands> replaces this
    default prefix with your own.

    For example, the following dial commands are the same:

    dial "5551212" with "ATDT";
    dial tone "5551212";

    4.  The <expression> is ended with a semi-colon and a carriage return.

    5.  The Progress box is displayed and the new expression is sent to the
    modem.

    6.  When the number has completed dialing, a dialog box is displayed
    indicating that it is Ok to pick up the phone.

    7.  After you select the <<Ok>> button from this dialog box, the text
    "ATH0" is sent to the modem and HyperPAD waits for the modem to respond
    "Ok".

    If dial is unsuccessful, you will receive an error message .

    This error is not a normal runtime error, however, and will not stop
    execution of your script. You can determine if an error occurred by
    using the result() function. The result() will be the text "not dialed"
    if there was an error, or empty if the dial was successful.

    If you have a Hayes incompatible modem, you can use the noHayes option
    to dial the phone. In this case, HyperPAD will not send any modem
    commands to your modem. The dial command performs the following steps:

    1.  The modem port is initialized using the current settings of the
    global properties modem, dataBits, stopBits, parity, and baud.

    2.  If you specified <modem commands>, HyperPAD will prefix it to
    <expression>.

    3.  HyperPAD sends the new expression to the serial port. HyperPAD will
    not wait for a response; it will return immediately.

    For example:

    dial nohayes "5551212";
    dial nohayes "D 5551212;" & return;

    The nohayes option is also useful to initialize your serial port.



    ________________________________________________________________________
                                               Chapter 11: Commands   110
    ________________________________________________________________________


    The following example uses dial to initialize the COM1 port to
    1200,N,8,1:

    set the modem to "com1";
    set the baud to 1200;
    set the parity to "none";
    set the stopBits to 8;
    set the dataBits to 1;
    dial nohayes empty;

    Examples:

    dial "315-463-1234";

    dial "315-463-1234" with "ATZ";

    dial pulse "9,18002341624";
    if result() is "not dialed" then
      answer "Can't dial the phone";

    The following example prompts for a number, then dials it. Special care
    is taken to check for an area code enclosed in parenthesis. This means
    that the number is long distance and should be preceded by a 1.

    ask "Number to dial:";
    if char 1 of it is "(" then
      begin
        -- get rid of parenthesis
        get substitute(it,"(","");
        get substitute(it,")","");
        -- long distance
        put 1 before it;
      end;
    get substitute(it," ","");
    dial it;
    if the result is not empty then
      answer "Error dialing the phone!";

    Note: The serial port is not initialized until you issue the dial
    command.

    See Also: baud, parity, stopBits, dataBits, modem



    ________________________________________________________________________
                                               Chapter 11: Commands   111
    ________________________________________________________________________


    -----------------------------------
    DIVIDE

    Syntax:
    divide <destination> by <expression>

    Purpose: The divide command divides <destination> by <expression> and
    places the result back into <destination>. The <expression> must be a
    number or a container holding a number. The <destination> must be a
    container.

    Note:  You will receive a runtime error if either the <destination> or
    the <expression> is not a number.

    Examples:

    divide page field 23 by 4;

    divide salesTax by 0.07;

    -----------------------------------
    DO

    Syntax:
    do <expression>

    Purpose: The do command compiles and executes the <expression>. This
    command provides a mechanism for executing statements from within a
    handler that haven't been compiled.

    The do command executes statements the same way as the message box.
    Thus, you can use the do command to evaluate expressions, putting the
    result into the message box. The following example puts the result of a
    calculation into the message box:

    do "3 + 4 - " && page field 1;

    You can only execute one command at a time. Thus, the <expression> can
    contain many statements.

    The do command must compile the specified statement, which may cause a
    slight delay in your script execution. The compiler must be located in
    the disk file "HPAD2.OVL", which must be accessible for this command to
    work.



    ________________________________________________________________________
                                               Chapter 11: Commands   112
    ________________________________________________________________________


    Examples:

    do "go to the next page";

    answer "Go where" with "next","previous";
    do "go to" && it && "page";

    The following statements execute the contents of field 1:

    do page field 1;

    -----------------------------------
    EDIT SCRIPT

    Syntax:
    edit [the] script of <object>;

    Purpose: This command is used to edit the script of different objects.
    This is the same as selecting the object's Info dialog box and selecting
    the  <Script...>  button.

    Examples:

    edit the script of page "Preferences";

    edit the script of page button 3;

    edit the script of background "Template";

    edit the script of pad;

    -----------------------------------
    FIND

    Syntax:
    find [part | whole] <expression> [in <field>];

    Purpose: The find command locates text anywhere in your pad. If you
    restrict the search to a single background field, only text on any page
    in that field will be locate. If you don't restrict the search to a
    particular background field, find will locate text in any field in your
    pad. (The find command will not locate text on the painting layer of the
    page or background.)

    HyperPAD searches differently for a part than it does for a whole. The
    whole option tells HyperPAD to locate only whole words; that is, only
    occurrences that are enclosed by word delimiters (such as spaces, end of



    ________________________________________________________________________
                                               Chapter 11: Commands   113
    ________________________________________________________________________


    lines, and punctuation) will be found. The part option tells HyperPAD to
    locate the text anywhere, even if it occurs within another word.

    For example, consider a field containing "John is a lawyer". The
    following statement will not find a match:

    find whole "law";

    The next statement, however, will find a match:

    find whole "is";

    Using find part, HyperPAD  will find occurrences anywhere within the
    target text, even if the expression occurs within a word. For example,
    consider the same text "John is a lawyer". The following statement will
    find a match:

    find part "law";

    Up to 10 strings can be specified. If more than one is given, find will
    locate any of the expressions in the destination. For example:

    find whole "john","joe","jack"

    After finding an occurrence, the user can press ENTER to search for the
    next instance of the string. If the user presses ENTER, the search
    begins on the current page where the previous find left off.

    If the user presses any other key, the search is terminated.

    If find locates a match within a locked field, you are taken to the page
    containing the match and the focus is set to the default object (because
    a locked field cannot receive the focus). If the user presses ENTER to
    locate the next match, the search begins on the next field after the
    locked one.

    If you use find from the message box, the Find in Progress box is
    displayed while HyperPAD searches; two beeps will sound if no matches
    are found. If you execute find from a script, the Find in Progress box
    and beeps won't occur.

    Determine the result of the find command using the result() function. If
    the find is successful, result will return "found". Otherwise, result
    will return "not found".

    Examples:

    To find John anywhere in the pad:

    find "John";



    ________________________________________________________________________
                                               Chapter 11: Commands   114
    ________________________________________________________________________


    To find John in the "first name" field:

    find "John" in field "First Name";

    The following button handler locates the next occurrence of the
    highlighted text. If the user hasn't highlighted any text, the Ask
    dialog box will appear and ask for something to find:

    handler select;
    begin
      get the selectedText;
      if it is empty then ask "Find What?";
      if it is empty then exit;
      find it;
      if the result is "not found" then
        answer "Can't find" && it with "Ok";
    end;

    -----------------------------------
    FLUSHCACHE

    Syntax:
    flushCache;

    Purpose: This command writes to disk all of the pages in memory that
    have been changed and empties the cache. Internally, HyperPAD keeps
    recently accessed pages in an area of the memory called the cache. When
    the cache becomes too large to fit in the memory, a page that hasn't
    been used in a long time is removed from the cache and written to disk.

    When to use it: Anytime you need more free memory for a particular
    operation, use this command. Also, use flushCache to prevent thrashing.
    (Thrashing is the constant disk access that occurs when the cache is
    full. For each new page read from the disk, a page must be written out.)

    Examples:

    flushCache;

    The following example frees up the maximum amount of memory before
    cycling through all of the pages in a pad:

    flushCache;
    for i = 1 to the number of pages do
      go to page i;

    Note: This command sends the flushCache message. The cache is flushed
    when the message is received by HyperPAD.

    See Also: maxDirtyPages, autoSave



    ________________________________________________________________________
                                               Chapter 11: Commands   115
    ________________________________________________________________________


    -----------------------------------
    FXSHOW

    Syntax:
    fxshow <fileName>;

    Purpose: This command is used to display images or screen shows from
    within HyperPAD. The fxshow command requires an external file called
    FXSHOW.EXE. The <fileName> parameter is the DOS filename of the .PRO,
    .PR2, .SLD, or .GX2 file you want to view.

    When HyperPAD loads for the first time, HyperPAD looks for the file
    FXSHOW.EXE in the same directory as HPAD.EXE. If the file is found, you
    will see an additional credit message displayed at the bottom of the
    screen informing you that fxshow is available. You cannot use the fxshow
    command if FXSHOW.EXE is not located in this directory.

    The fxshow command causes HyperPAD to shrink down to 3K and run the
    program FXSHOW.EXE, passing it information about what files to load.
    Refer to Appendix 4, "Support for Show Partner F/X" for more
    information.

    When running the show, HyperPAD does the following:

    1.  Switches to the directory containing <fileName>.

    2.  If no extension is specified, searches for files in this order:
    *.PRO, *.PR2, *.SLD, *.GX2.

    3.  Issues the suspend message to run FXSHOW.EXE.

    4.  Runs the show.

    5.  Returns control to HyperPAD.

    This is very similar to running a program with the run command, except
    that HyperPAD first changes to the directory containing the files you
    run.

    Examples:

    fxshow "sample";

    fxshow "C:\FX\SAMPLE\SAMPLE";

    fxshow "d:\pics\*.gx2";

    Note: This command sends the fxshow message. The handler for this
    message is implemented in HyperPAD.



    ________________________________________________________________________
                                               Chapter 11: Commands   116
    ________________________________________________________________________


    -----------------------------------
    GET

    Syntax:
    get <expression>;

    Purpose: Use get to retrieve a value and put it into the local variable
    it. The <expression> can be a constant, a literal, a function, or a
    container (the value of a variable, a field's contents, or the contents
    of the message box).

    Examples:

    get 1 + 2 * 3;

    get field 1 of page 25;

    get word 1 to 5 of line 6 of field id 2 of page 88;

    Using the local variable it will enhance script readability and
    execution speed, as shown in the following example:

    get the selectedText;
    if it is empty then ask "What do you want to find?";
    if it is empty then exit;
    find it;

    See Also: put

    -----------------------------------
    GLOBAL

    Syntax:
    global <var1> [<var2>,...];

    Purpose: The global statement allows you to declare a global variable. A
    Global variable is accessible to all handlers, not just the handler in
    which it is defined. Global variables remain until you exit HyperPAD or
    run another program.

    Note:  The global command cannot be used in a do command or in the
    message box.

    When to use it:  If you want a particular variable to maintain its value
    between handlers or pads, you must define it as a global variable.

    Examples:

    global taxAmount,salesAmount,userName;



    ________________________________________________________________________
                                               Chapter 11: Commands   117
    ________________________________________________________________________


    -----------------------------------
    GO

    Syntax:

    go [to] [pad] <padName> [with diskChange <expression>];
    go [to] <background> [of [pad] <padName> [with diskChange
    <expression>]];
    go [to] <page> [of <background>] [of [pad] <padName> [with diskChange
    <expression>]];
    go back;
    go help;
    go home;

    Purpose: The go command changes to another page, background or pad. The
    destination indicates which page (and if necessary, which pad) will be
    displayed. If the destination specifies only a pad, HyperPAD goes to the
    default page (the page which was last accessed) of that pad. You can
    alter the destination by supplying a container as the destination.

    The diskChange option allows you to specify that the destination pad may
    be on a different disk. In this case, the user will be asked to switch
    disks using the <expression> that you supply as a prompt. For example:

    go to pad "a:phone" with diskChange "Insert Disk 2";

    When you supply the diskChange parameter:

    1.  The current pad is closed.

    2.  HyperPAD displays a dialog box with the message the you supplied.

    3.  The user can then remove a disk and insert the disk containing the
    desired pad. If the user selects <<Ok>>, HyperPAD will attempt to load
    the pad from the new disk.

    If the user is unable to insert the correct disk and presses <Cancel> at
    the dialog box, HyperPAD will attempt to load the original pad. If
    unable to do so, HyperPAD will ask the user to insert the original
    disk...and will continue to do so until the original disk has been
    inserted.

    The go home and go help statements are special because they use
    HyperPAD's special file searching method to locate the pad.



    ________________________________________________________________________
                                               Chapter 11: Commands   118
    ________________________________________________________________________


    The statement

    go to pad "HOME";

    may not be unable to locate the Home pad because it may not be in the
    current directory or path. Thus, if you want to access either the Home
    or Help pads you should use go home and go help.

    go back - is the same as selecting Back from the Go menu.

    go recent - goes to the most recently accessed page (the one that you
    just came from).

    You can also use ordinal types with the go command. The allowed ordinal
    types are:

    first, second, third,...,tenth
    next
    previous
    any
    middle
    this
    recent

    If you attempt to go to a page beyond the end of the pad, the result()
    function will return "no such page"; otherwise, it will return empty.

    Examples:

    go to page 1;

    go to page 1 of background 2;

    go to background "template";

    go "phone";

    go to pad "phone";

    go to pad "phone" with diskChange "Insert Disk 2";

    go to page 2 of pad "Phone";

    go to page 1 of background 2 of pad "Phone" with
       diskChange "Insert Disk 2";

    go to the next page;

    go to page (currentPage() + 10);

    go to page ("taxNumber" && i);



    ________________________________________________________________________
                                               Chapter 11: Commands   119
    ________________________________________________________________________


    go to any page;

    go to the recent page;

    go to the first page of pad "Phone"

    ask "Go to what pad?";  -- ask for a name
    go to pad it;

    ask "Go to what page?";  -- ask for name or number
    go to page it;

    Note: Remember, pads are only referenced by name. Thus, the only way to
    go to a pad is to supply the DOS name of the pad:

    go to pad "phone";

    Pages and backgrounds, however, can be referenced by either their number
    within the pad, their ID, or their name. For example:

    go to page 10;       -- by page number

    go to page id 56;    -- by page ID

    go to page "status"; -- by page name

    When going to backgrounds, HyperPAD really goes to pages on the
    specified background. The following list summarizes what happens with
    different go statements involving backgrounds:

    The following statement goes to the first page on the first background
    that you created.

    go to background 1;

    The next statement goes to the first page after the current page that is
    on a different background.

    go to the next background;

    The next statement goes to the fifth page that uses background 2.

    go to page 5 of background 2;

    The next statement goes to the next page after the current page that
    uses the same background.

    go to the next page of this background;



    ________________________________________________________________________
                                               Chapter 11: Commands   120
    ________________________________________________________________________


    -----------------------------------
    HIDE

    Syntax:
    hide <object>;

    Purpose: The hide command allows you to make the specified button or
    field invisible. This command actually modifies the visible property of
    the target object. In fact, the following two statements are equivalent:

    hide page button 1;

    set the visible of page button 1 to false;

    When to use it:  If you want a button or field to become visible only
    when certain criteria are met, you can use hide and show to toggle the
    object's visibility.

    Examples:

    hide page field 1;

    hide background button 3;

    See Also: show, visible

    -----------------------------------
    HILITE

    Syntax:
    hilite [<chunk>];
    hilite <field>;
    hilite the message box;

    Purpose: This command highlights text within a field or the message box.
    The text that gets highlighted is copied into the selectedText.

    When highlighting text, the text becomes highlighted on the screen.



    ________________________________________________________________________
                                               Chapter 11: Commands   121
    ________________________________________________________________________


    Examples:

    hilite char 1 to 5 of page field 1;

    hilite line 1 of page field 1;

    hilite the last line of me;

    hilite field "Last Name";

    hilite the message box;

    hilite word 2 of msg;

    The following example locates the word "lawyer" in a field and
    highlights it.

    get offset("lawyer",field "occupation");
    if it is 0 then exit;
    hilite char it to (it + 5) of field "occupation";

    See Also: selectedText

    -----------------------------------
    MULTIPLY

    Syntax:
    multiply <destination> by <expression>;

    Purpose: This command multiplies the value of the <destination> by the
    value of the <expression> and places the result into the <destination>.
    The expression must be a number or a container holding a number. The
    destination must be a container.

    Note:  You will receive a runtime error if the <destination> or the
    <expression> are not
    both numbers.

    Examples:

    multiply page field 1 by 6;

    multiply totalAmount by salesTax;

    multiply the message box by 10;

    See Also: add, subtract, divide



    ________________________________________________________________________
                                               Chapter 11: Commands   122
    ________________________________________________________________________


    -----------------------------------
    NOSOUND

    Syntax:
    noSound;

    Purpose: This command stops any music or tones that are currently being
    played.

    Examples:

    sound 2000;    -- start a sound
    wait 200;      -- 200 milliseconds
    noSound;       -- turn it off

    The following example plays notes for 5 seconds.

    play "abcdefg";
    wait 5000;
    noSound;

    Note: This command sends the noSound message which is implemented in
    HyperPAD.

    -----------------------------------
    PLAY

    Syntax:
    play <expression>;

    Purpose: The play command allows you to play music in the background
    while other HyperPAD tasks are taking place.



    ________________________________________________________________________
                                               Chapter 11: Commands   123
    ________________________________________________________________________


    The <expression> is a string containing note and music commands:

    Command:   Description:
    -----------------------------------------------------------------
    A-G        Play this note.

    +,#        Make the preceding note sharp.

    -          Make the preceding note flat.

    Ln         Set the length of each note to n. L1= full note, L2 = 1/2
               note, L3= 1/4 note (default). The range of n is 1 to 64.

    MN         Play normal. Each not will play 7/8 of the time given by L.

    ML         Music legato. Each note will play the full time given by L.

    MS         Music staccato. Each note will play 3/4 of the time given by
               L.

    On         Sets the current octave to n. The default is 2, the range of
               octaves is 0 to 6. Middle C is at the beginning of octave 3.

    Pn         Pause = n. The range of n is 1 to 64.

    Tn         Tempo = n. This sets the number of L4 quarter notes in one
               minute. The range of n is 32-255. The default is 120.

    >n         Increases the octave of the next note by 1.

    <n         Decreases the octave of the next note by 1.

    .          Increases the playing time of the note (L*T) by 50%. Multiple
               periods can appear after a note (multiples the playing time
               by 3/2). Periods may also appear after a pause.

    Note:  Any spaces in your play string are ignored.

    Music continues to play in the background until there are no more notes
    to play. You can stop the music by issuing a noSound command. You can
    determine if music is playing using the isSound() function.

    Examples:

    play "cdefgabc";

    play "O1 L16 T12O A O2 P4.. B.";

    Notes: This command sends the play message. When the message is received
    by HyperPAD, the music will begin playing in the background.

    See Also: noSound, isSound()



    ________________________________________________________________________
                                               Chapter 11: Commands   124
    ________________________________________________________________________


    -----------------------------------
    PLAYBACK

    Syntax:
    playBack;

    Purpose: The playBack command starts the replay of keys that have
    previously been recorded using the record command.
    HyperPAD begins executing a playBack command on the next idle message.

    If keys are played back within HyperPAD, the first key will be pressed
    at the beginning at the next idle (when HyperPAD checks for key
    presses). The real power, however, is in HyperPAD's ability to play back
    keys while other programs are running, like in the following example:

    record "/frHOUSE.WK1{enter}";
    playback;
    run "C:\LOTUS\123.EXE" with programDirectory;

    Note: This command sends the playBack message. The playBack command is
    executed when this message is received by HyperPAD.

    See Also: record

    -----------------------------------
    POP PAGE

    Syntax:
    pop page [into <container>];

    Purpose: The pop page command removes the last pushed page from the page
    stack and either goes to it or places it into a container.

    The push page command allows you to remember where you are in your pad
    as if you had placed a bookmark on that page.
    Then, when you want to return there, you use the pop page command. You
    can place a series of these bookmarks, in which case pop page will take
    you to those pages in the reverse order in which you placed them.



    ________________________________________________________________________
                                               Chapter 11: Commands   125
    ________________________________________________________________________


    If you use the form

    pop page;

    you will actually be taken there (you will change pages and possibly the
    pad). You can also put the references to that page into a variable:

    pop page into pageRef;

    pageRef will contain a page reference similar to the following:

    page id 2 of pad "C:\HOME.PAD";

    Examples:

    The following statements show several different uses of the page stack.
    The first example remembers the current page, fetches the user's name
    from the Home pad, and returns.

    push this page;
    go home;
    go to page "preferences";
    put page field "User Name" into userName;
    pop page;

    push recent;
    pop page into pageRef;
    get the last word of pageRef;
    go to the first page of pad it;

    See Also: push page

    -----------------------------------
    PRINT

    Syntax:
    print <expression> [at <x>,<y>];
    print <page reference>;
    print <number> pages;

    Purpose: The print command prints either a page, a group of pages, or an
    expression at an optional X,Y location.

    Printing pages within HyperPAD is controlled by the current settings in
    the Print Page dialog box, the Page Setup dialog box, and the Printer
    Setup dialog box. Printing pages with the print command is exactly the
    same as choosing Print from the File menu and selecting the Pages
    option.



    ________________________________________________________________________
                                               Chapter 11: Commands   126
    ________________________________________________________________________


    For example:

    print page 1;

    print page "status";

    print the next page;

    print 10 pages;

    Printing text, on the other hand, is not controlled by the current print
    settings. You must turn the printer on and off manually (using the
    printer property) and eject pages by sending formfeeds from your script.
    The following steps are taken:

    1.  Turn the printer on.

    2.  Do your printing.

    3.  Turn the printer off.

    The print command keeps track of the printhead position internally. When
    you first turn the printer on, the print head is positioned at 1,1 on
    the page. As you print characters across the page, the print head X
    position changes to different coordinates, such as 10,1. As you print
    carriage returns, the X position is reset to 1 and the Y position is
    incremented, like 1,10. When you print an end of page (formfeed) the
    print head position is reset to 1,1.

    You can directly locate the print head using the print at syntax. For
    example:

    print "hello world" at 10,10;

    When using this syntax, you can only move the print head to the right on
    the current line or down on the page. The printhead cannot backtrack
    over already printed text.

    Examples:

    print page field 1;

    print page field 1 & return & page field 2;

    print formfeed;

    print page field "First Name" at 10,10;



    ________________________________________________________________________
                                               Chapter 11: Commands   127
    ________________________________________________________________________


    The following example prints the AUTOEXEC.BAT file:

    set the printer to on;
    put open ("C:\AUTOEXEC.BAT") into fh;
    if the result is not empty then exit;
    while the result is not "eof" do
      begin
        read 1 line from fh;
        print it & return;
      end;
    set the printer to off;
    close fh;

    The following handler prints all the page fields in a pad:

    handler select;
    begin
      ask "Which pad?" with currentPad();
      if it is empty then exit;
      go to pad it;
      for i = 1 to the number of pages do
        begin
          go to page i;
          for j = 1 to the number of pg flds do
            print page field j & return;
        end;
    end;

    -----------------------------------
    PUSH

    Syntax:
    push <page description>;
    push recent;

    Purpose: The push page command saves a page identifier on the page
    stack. The push page command remembers a page and pad so that you can
    later return there with the pop page command. You can think of this
    command as placing a bookmark at a location within a pad.



    ________________________________________________________________________
                                               Chapter 11: Commands   128
    ________________________________________________________________________


    The push recent syntax saves the page that you just came from on the
    page stack.  This is particularly useful for returning back there later,
    like in the following example:

    This handler belongs in a pad script.

    handler openPad;
    begin
      push recent;
      pass;
    end;

    When you want to return from where you came:

    handler select;
    begin
      pop page;
    end;

    When to use it:  Use the push page command when you want to remember a
    particular location within a pad so that you can later return there.

    Examples:

    The following script visits every page of a background, sending a
    message to one of its fields and then returns to the page it started
    from.

    handler select;
    begin
      put 0 into total;
      push this page;
      for i=1 to the number of pages of bkgnd 2 do
        begin
          go to page i of bkgnd 2;
          send "reCalc" to field "Item Cost";
          add pg fld "Item Cost" to total;
        end;
      pop page;
      answer "The total was" && total;
    end;

    Some other examples:

    push this page;

    push recent;

    push previous page;

    push next page;



    ________________________________________________________________________
                                               Chapter 11: Commands   129
    ________________________________________________________________________


    push first page;

    push page 2 of bkgnd 4;

    See Also: pop page

    -----------------------------------
    PUT

    Syntax:
    put <expression> [into <destination>];

    Purpose: The put command places information into a container: either a
    field, a variable, or the message box. The <expression> can be text,
    numeric, a numeric expression, or a container. The <destination> must be
    a container.
    Expressions are evaluated before they are stored in the destination. So,
    if you put an arithmetic equation, its result is placed into the
    destination.

    If no destination is specified the result is placed into the message
    box.

    The put command is probably the most often used command in PADtalk. It
    provides the only mechanism for copying data from one location to
    another.

    Examples:

    put 10 into page field 1;

    put longDate() into the message box;

    put "Wowee" after word 7 of pg fld id 8;

    put page field "subTotal" into page field "total";

    put 10 into field 1 of page 6 of background 2;

    put empty into me;

    The following two statements are the same:

    put "hello";
    put "hello" into the message box;

    The next two statements are also the same:

    put "hello" into it;
    get "hello";

    See also: get



    ________________________________________________________________________
                                               Chapter 11: Commands   130
    ________________________________________________________________________


    -----------------------------------
    QUERY

    Syntax:
    query <expression>;
    query clear;

    Purpose: The query command creates a subset of pages based on some
    criteria. The query command goes to each page of a particular background
    and evaluates a boolean (true or false) expression. If the expression is
    true, then the page is included in the query. If the expression is
    false, then the page is excluded from the query. A subset of the pages
    that meet the criteria is formed.

    The following example will include only pages that contain "John" in the
    "name" field.

    query field "Name" contains "John";

    If you want to query on a numeric field:

    query field "Total" > 10;

    The following statement shows the versatility of the query command. It
    results in a random set of about half of the pages of any background
    being included in the query.

    query random(2) = 1;

    Once the query has been established, the pad user can view only those
    pages included in the subset. Using the built-in navigation tools
    (including PGUP and PGDN), the user can move between the pages in the
    group. While a query is active, the user can also print and sort those
    pages.

    Although you can use PADtalk commands to access other pages in the pad,
    in order to restore the pad to its pre-query state, you must clear the
    query with the query clear command.

    The query will also be cleared if you perform another query, exit to
    DOS, or run another program.

    For larger queries, HyperPAD may be required to create a temporary file
    to hold some query information. The file will reside in the program
    directory (where HPAD.EXE is located) and will have the same name as
    your current pad but with an ".IDX" file extension.

    The result of the query can be determined using the result() function.
    The result() will return "found" if the query found at least one page;
    otherwise the result() will return "not found".



    ________________________________________________________________________
                                               Chapter 11: Commands   131
    ________________________________________________________________________


    Examples:

    query field 1 contains "Smith";
    if the result is "not found" then
      answer "No pages in query.";

    query field 1 = 3 and field 2  10;

    query field 1 = 3 and field 2  10 or state = "NY";

    See Also: find, sort

    -----------------------------------
    READ

    Syntax:
    read from <fileNumber> until end;
    read from <fileNumber> until <character>;
    read <expression> characters | items |
         words | lines from <fileNumber>;

    Purpose: The read command reads data from a file into the local variable
    it. You can only read from files that have been opened using the open()
    function.

    The syntax read from <fileNumber> until end is used to read all the
    characters that remain in the file starting at the current position in
    the file.

    put open("data.dat") into fh;
    read from fh until end;
    close fh;
    put it into field 1;

    The syntax  read from <fileNumber> until <character> is used to read all
    of the characters up to the next occurrence of character starting at the
    current position. For example:

    put open("data.dat") into fh;
    read from fh until "A";
    close fh;
    put it into field 1;

    The syntax read <expression> characters | items | words | lines from
    <fileNumber> is used to read a number of characters, words, items, of
    lines from the file into the variable it.



    ________________________________________________________________________
                                               Chapter 11: Commands   132
    ________________________________________________________________________


    For example:

    put open("data.dat") int fh;
    read 1 character from fh;
    put it;
    read 6 words from fh;
    put it;
    read 5 items from fh;
    put it;
    read 2 lines from it;
    put it;

    Words are surrounded by either spaces or carriage returns, items are
    determined by commas, and lines are defined by carriage returns.

    When reading from files, HyperPAD translates carriage return/line-feed
    pairs to single carriage returns.

    You can determine if you have reached the end of file using the result()
    function. If you have reached the end of file, the result() returns
    "eof". Otherwise, the result() will be empty. The end of file is
    determined by either an end of file marker (Hex 1A) or by reading the
    number of characters determined by the file size. For example:

    Examples:

    read from file_number until end;

    read from file_number until "@";

    read n+1 words from file_number;

    read 1 line from file_number;

    This example reads the AUTOEXEC.BAT file into page field 1:

    put the open of "C:\AUTOEXEC.BAT" into fh;
    read from fh until end;
    close fh;
    put it into page field 1;

    The next handler reads a text file of names and addresses into the PHONE
    pad. Each record in the text file is separated by a blank line. The
    format of the phone record in the text file is as follows:
       Name
       Phone Number
       Address
       Name
       Phone Number
       Address



    ________________________________________________________________________
                                               Chapter 11: Commands   133
    ________________________________________________________________________


    The address field can take up as many lines as necessary, as long as a
    blank line is understood as separating the records:

    handler readPhoneRecords;
    begin
      put open ("PHONE.TXT") into fh;
      repeat
        doMenu "new page";
        read 1 line from fh;
        put it into field "Name";
        read 1 line from fh;
        put it into field "Phone Number";
        read 1 line from fh;
        put empty into "Address";
        repeat
          read 1 line from fh;
          if it is not empty then
          put it after the last line of address;
        until it is empty;
        put address into field "Address";
      until the result is "eof";
      close fh;
    end;

    Note: The <fileNumber> parameter is a number returned by the open()
    function.

    See Also:  write, create(), append(), open()

    -----------------------------------
    RECORD

    Syntax:
    record <expression>;

    Purpose: This command records keystrokes for later playback using the
    playBack command. The number of keystrokes you can record is 100.

    Recorded keystrokes remain in memory when you run other programs. If
    there are any keys in the buffer when another program is launched, they
    are immediately played back when the running program is started.

    The <expression> contains the keystrokes that you want played back.
    Letters and punctuation are types in as normal, like:

    record "hello";

    Special keys and key combinations are placed inside brackets, like:

    record "{alt+f}Njunk.pad{enter}";



    ________________________________________________________________________
                                               Chapter 11: Commands   134
    ________________________________________________________________________


    A complete list of all of the special keys and key combinations is
    located in Appendix 2, "Key Codes". The record command will translate
    all of the keys in the <expression>  to numbers.

    In addition to keystrokes, there is a special command that you can place
    within brackets called pause. For example:

    record "{escape}{enter}{pause:5000}";

    The pause command waits a specified number of milliseconds before
    continuing keystroke playback. Thus, {pause:500} waits for half a
    second.

    When to use it:  When combined with the run command, the record and
    playback commands are particularly useful because you can pump
    keystrokes into other programs.

    Examples:

    record "this is a test";

    record "{alt+f}ophone{enter}";

    The following runs BASICA, loading a program called DEMO and running it:

    handler select;
    begin
     record "load ^"DEMO.BAS^"{enter}run{enter}";
     playBack;
     run "BASICA.EXE";
    end;

    Notes: This command sends the record message. HyperPAD handles the
    record message.

    See Also: playBack

    -----------------------------------
    RUN

    Syntax:
    run <program>;
    run <program> with programDirectory;
    run <program> with pause;
    run <program> with programDirectory,pause;

    Purpose: The run command executes other programs you use on your
    computer. While the external program is running, HyperPAD shrinks to 3K,



    ________________________________________________________________________
                                               Chapter 11: Commands   135
    ________________________________________________________________________


    giving the program as much memory as possible. When you exit the
    external program, HyperPAD resumes where it left off.

    The pause parameter causes HyperPAD to display the message

    Press any key to return to HyperPAD

    before returning to HyperPAD.  HyperPAD will resume after any keystroke
    or mouse button press.

    The programDirectory option controls which directory the program will be
    executed from. If specified, the current directory will be changed to
    the directory containing the program. If it is not specified, the
    current directory will remain unchanged. This parameter is used mainly
    with programs that require you run them from their own directory.

    When running another program, HyperPAD performs the following steps:

    1.  If the extension is not supplied, HyperPAD looks for .EXE, .COM, and
    .BAT files.

    2.  If a directory is specified with the filename, HyperPAD looks only
    in that directory for the program.

    3.  If no directory is specified, HyperPAD searches the following areas
    (in this order) for the program:

    a. The current directory.
    b. The directory specified by the environment variable HPADNET.
    c. The program directory (where HPAD.EXE is located).
    d. The startup directory (where HPAD.EXE was started from).
    e. Every directory specified in the path.

    You can determine the return code of the a program using the result()
    function. Normally, you can determine the return code of a program in a
    batch file using the DOS errorlevel batch command. In HyperPAD, this
    number is returned by the result() function.

    Examples:

    To return temporarily to the MS-DOS prompt:

    run environment("COMSPEC");

    To run a standard program:

    run "C:\123\123.EXE" with programDirectory;

    To run a batch file called C:\BATS\TEST.BAT:

    run "C:\COMMAND.COM /c C:\BATS\TEST.BAT";



    ________________________________________________________________________
                                               Chapter 11: Commands   136
    ________________________________________________________________________


    To run a batch file leaving room for a larger environment:

    run "C:\COMMAND.COM /e:2048 /c C:\BATS\TEST.BAT";

    To run a program and pause before it returns:

    run "FORMAT.COM A:" with pause;

    Abbreviations: programDir, progDir

    -----------------------------------
    SEND

    Syntax:
    send <message> <parameter list> to <object>

    Purpose: The send command sends a message, along with its parameters, to
    a specific object. It allows you to redirect a message's normal travel
    up the hierarchy to another object.

    When to use it: Use the send command when you want some action to be
    performed that is handled by some other object or handler.
    It can also be used to bypass a message handler in the hierarchy.

    Parameters: The <message> parameter is any message for which a handler
    has been defined in the hierarchy of the receiving object.  The
    characters of the message must be enclosed in double quotes, like
    "select". The optional <parameter list> is a list of  values separated
    by commas that will be used by the receiving message handler.

    Examples:

    send "select" to page button "Quit";

    send "keyPress" 7181 to me; -- simulate ENTER

    send "changeTemp" "up",5 to fld "Thermostat";

    The following statement avoids the other objects in the hierarchy by
    sending a message directly to HyperPAD:

    send "doMenu" "new page" to hyperpad;

    The send message will travel up the hierarchy of the receiving object.



    ________________________________________________________________________
                                               Chapter 11: Commands   137
    ________________________________________________________________________


    The following example sends a message to one of two routines. It either
    adds or multiplies two numbers, depending on which option the user
    wants:

    handler _add(n1, n2);
    begin
      put n1 + n2;
    end;

    handler _multiply (n1,n2);
    begin
      put n1 * n2;
    end;

    handler select;
    begin
      answer "add or multiply" with "add", "multiply";
      if it is not empty then
        send "_" & it 10,12 to me;
    end;

    Note: The send command changes the value of the me object, but does not
    change the value of target or currentObject. You can only send messages
    to objects within the current pad. If you send a message to another
    page, that page does not become the current page (i.e. it will not
    receive the openPage message). Parameter expressions are evaluated
    before the message is sent.

    -----------------------------------
    SET

    Syntax:
    set [the] <property> [of <object>] to <value>;

    Purpose: The set command establishes property values of the objects in
    your pads. With set, you can modify properties affecting buttons,
    fields, pages, backgrounds, pads, the message box, the menu bar, the
    status bar and the tool box.

    The properties that you can set for the different objects are described
    in Chapter Twelve, "Properties".

    Examples:

    set hilite of page button 1 to true;

    set lockScreen to false;

    set the color of page field 4 to black on white;



    ________________________________________________________________________
                                               Chapter 11: Commands   138
    ________________________________________________________________________


    -----------------------------------
    SETDEFAULTPOPUPCOLOR

    Syntax:
    setDefaultPopupColor;

    Purpose: This handler resets the colors of the popup menus to the same
    values that HyperPAD uses to display the pull down menus. These colors
    are modified depending on your computer's graphics card and the command
    line parameters /mono, /lcd, /B&W, and /color.

    See Also: popup(), setPopupColors

    -----------------------------------
    SETPOPUPCOLORS

    Syntax:
    setPopupColors <menu color>,<highlight color>,
      <letter color>,<dimmed color>;

    Purpose: This handler sets the display colors for future popup menus.
    The colors are used as follows:

    Color:             Description:
    ----------------------------------------------------
    Menu color         The color of the menu, including the border

    Highlight color    The color of a highlighted choice

    Letter color       The color of the accelerator characters of the
                       choices (specified with the & within the choice)

    Dimmed color       The color of dimmed choices (specified with the @
                       character within the choice)

    Examples:

    setPopupColors 31,112,27,123;

    setPopupColors light green,black on grey,red,light grey;

    See Also: popup(), setDefaultPopupColors



    ________________________________________________________________________
                                               Chapter 11: Commands   139
    ________________________________________________________________________


    -----------------------------------
    SHOW

    Syntax:
    show <object>;

    Purpose: The show command makes the specified button or field visible;
    this is the same as setting the visible property of the object to true.

    When to use it:  If you want a button or field to become visible only if
    certain criteria are met.

    Examples:

    show page button 3;

    show page field 7;

    The following two statements are equivalent:

    show button 1;

    set the visible of button 1 to true;

    See Also: hide, visible

    -----------------------------------
    SORT

    Syntax:
    sort [ascending | descending] [text | numeric | date]
      by <expression>;

    Purpose: The sort command reorders the pages belonging to a background
    according to a specified condition.

    The sort command works by cycling though all the pages of a particular
    background and evaluating an expression. The result of the expression is
    saved and used as a sort key. Once all of the sort information has been
    gathered, the pages are sorted in the specified order.

    For example, the following statement sorts a pad by the first background
    field:

    sort by field 1;

    For each page in the current background, the expression field 1 is
    evaluated and used as sort criteria. Suppose that there are 5 pages in
    this pad, each using the same background.



    ________________________________________________________________________
                                               Chapter 11: Commands   140
    ________________________________________________________________________


    After sort has cycled through all of the pages and evaluated the
    expression, the situation is as follows:

    at page 1, field 1 = "Sue"
    at page 2, field 1 = "John"
    at page 3, field 1 = "Zev"
    at page 4, field 1 = "Lisa"
    at page 5, field 1 = "Jim"

    After sorting, the pages will be reordered as follows:

    page 5 will become page 1  ("Jim")
    page 2 will become page 2  ("John")
    page 4 will become page 3  ("Lisa")
    page 1 will become page 4  ("Sue")
    page 3 will become page 5  ("Zev")

    When there are multiple backgrounds in the pad, sort may appear to give
    incorrect results because pages in the pad that use different
    backgrounds will remain in their same positions. For example, suppose we
    have 7 pages, 5 pages using background 1 and 2 pages using background 2.
    We perform the same sort on the first page of background 1:

    page 1, background 1, field 1 = "Sue"
    page 2, background 2
    page 3, background 1, field 1 = "John"
    page 4, background 1, field 1 = "Zev"
    page 5, background 2
    page 6, background 1, field 1 = "Lisa"
    page 7, background 1, field 1 = "Jim"

    After sorting, the pad will be organized as follows (notice that the
    pages of background 2 remained in their relative positions in the pad):

    page 7, background 1  ("Jim")
    page 2, background 2
    page 3, background 1  ("John")
    page 6, background 1  ("Lisa")
    page 5, background 2
    page 1, background 1  ("Sue")
    page 4, background 1  ("Zev")

    The sort command treats the data differently if you specify text,
    numeric, or date. For text data, HyperPAD alphabetizes the data. For
    numeric data, HyperPAD compares numeric quantities. For dates, HyperPAD
    compares the data as dates (dates can be represented using any format
    the convert command recognizes).



    ________________________________________________________________________
                                               Chapter 11: Commands   141
    ________________________________________________________________________


    The optional parameter ascending (the default) specifies that you want
    the data sorted with the lowest values near the front; descending
    specifies the opposite.

    For larger sorts, a disk file may be required to hold temporary sorting
    data. In such a case, HyperPAD creates a temporary file in either the
    directory specified by the TMP environment variable, or if TMP is not
    specified, in the directory from which you launched HyperPAD.

    To make sorting faster, therefore, you can have TMP specify a directory
    on a RAM disk, as in the following DOS command:

    SET TMP=D:\

    Examples:

    sort descending by field "name";

    sort by the last word of field "name";

    sort numeric by field "age";

    sort ascending date by field "birthday";

    See Also: query, find

    -----------------------------------
    SOUND

    Syntax:
    sound <frequency>;

    Purpose: The sound command turns the speaker on at a given frequency.

    The sound will remain on until you turn it off using the noSound
    command.

    Examples:

    sound 2000;
    wait 500;  -- half a second
    noSound;

    Notes: This command sends the sound message. When the handler reaches
    HyperPAD, the sound handler is executed.



    ________________________________________________________________________
                                               Chapter 11: Commands   142
    ________________________________________________________________________


    -----------------------------------
    SUBTRACT

    Syntax:
    subtract <expression> from <destination>;

    Purpose: The subtract command subtracts the value of the expression from
    the value of the destination and places the result into the destination.
    The <expression> must be a number or a container holding a number. The
    <destination> must be a container.

    Note:  You will receive a runtime error if the <expression> and
    <destination> are not both numbers.

    Examples:

    subtract 5 from page field 23;

    -----------------------------------
    VISUAL

    Syntax:
    visual [effect] <effectName> [<direction>]
      [with delay <expression>];

    Purpose: The visual command sets up an effect to be used during the next
    page or pad change. Instead of simply replacing one page with another
    (which is the default) you can select an effect which alters the manner
    in which a page is placed on-screen.

    Once the effect has been executed, it is reset to the replace effect
    (the default). So, you must specify an effect each time you want it to
    occur.

    The following list includes all the effects and their usable directions:

    Effect:        Direction:
    ----------------------------------------------------------
    box            in, out

    drip           none

    fade           none

    hsplit         in, out

    peel           upperleft, lowerleft, upperright, lowerright

    quad           none

    replace        none



    ________________________________________________________________________
                                               Chapter 11: Commands   143
    ________________________________________________________________________


    When to use it: Visual effects are useful if you want to capture your
    audience's attention without distracting them from the information
    you're relating.

    Examples:

    The following example goes to the next or previous page depending on
    whether the SHIFT key is depressed when the button was selected. It uses
    an appropriate visual direction as a user feedback device.

    handler select;
    begin
      if the shiftKey is "down" then
        begin
          visual effect scroll down;
          go to the previous page;
        end
      else
        begin
          visual effect scroll up;
          go to the next page;
        end
    end;

    Comments: The visual effect is set to replace when the next idle message
    is sent (upon completion of all pending handlers).

    -----------------------------------
    WAIT

    Syntax:
    wait <milliseconds>;

    Purpose: This command waits a specified number of milliseconds. Pressing
    CTRL+BREAK will terminate the wait command and stop execution of the
    script.

    The delay is the same for all computers. HyperPAD uses either the real
    time clock (on AT style computers) or the system clock (interrupt 8) so
    that it ticks 1000 times per second.

    Examples:

    wait 5000;     -- 5 seconds

    wait i * 1000; -- if i = seconds



    ________________________________________________________________________
                                               Chapter 11: Commands   144
    ________________________________________________________________________


    -----------------------------------
    WRITE

    Syntax:
    write <expression> to <fileNumber>;

    Purpose: The write command adds data to an open file. Only files opened
    with the append() or create() function can be used with this command.

    Examples:

    To write a field to a file:

    put create("data.dat") into fh;
    write page field 1 to fh;
    close fh;
    Use the return constant to end a line:

    write page field "name" & return to fh;
    write page field "address" & return to fh;
    write page field "phone number" & return & return to fh;

    Note: Single carriage returns are translated to carriage return/line-
    feed pairs. All files are automatically closed when the user exits or
    runs another application using the run command.